home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 26 / Cream of the Crop 26.iso / bbs / pentas20.zip / PENTAS20.EXE / DOCS / SCRIPTS.DOC < prev    next >
Text File  |  1997-08-20  |  39KB  |  882 lines

  1.      * P E N T A S I M *
  2.         S C R I P T S
  3.      
  4.              
  5.              TABLE OF CONTENTS
  6.             ─────────────────────────────────────────────────────
  7.              Introduction.......................................1
  8.              How Scripts Work...................................2
  9.              Using SCRIPTS.EXE..................................3
  10.              Unregistered Limits................................4
  11.              Writing Scripts....................................5
  12.              Color Codes........................................6
  13.              Script Example.....................................7
  14.              Distributing Scripts...............................8
  15.              Script Errors......................................9
  16.              Final Word........................................10
  17.             ─────────────────────────────────────────────────────
  18.      
  19.      
  20.      
  21.      ┌─INTRODUCTION──────────────────────────────────────────────────┐
  22.      └───────────────────────────────────────────────────────────────┘
  23.  
  24.       Many door games on the market right now have the ability to 
  25.       utilize 3rd party IGM's or EPM's as I like to call them.  Some 
  26.       even allow for Sysop's to write their own Scripts using a chosen 
  27.       Script environment for each different product.
  28.  
  29.       I have found that for the most part, some of the Scripting that 
  30.       can be done is so complex in some instances, that the Sysop might 
  31.       as well learn to program :)  In an effort to write something that 
  32.       ALL Sysop's could easily use, I have come up with a Scripting 
  33.       Language for Pentasim that should prove easy for most Sysop's.  
  34.       It is not as complex to learn so of course it does give way to 
  35.       some configurability.
  36.  
  37.       That's not to say the Scripting is no fun, or it does not provide 
  38.       a means for the Sysop to customize their game...It just may not be 
  39.       as extensive as some other Scripting that can be done.  It's still 
  40.       fun though folks...and should be fairly easy for all to learn and 
  41.       use.
  42.  
  43.       ****PLEASE: Do us both a favor and read this ENTIRE file before 
  44.                   contacting me saying "It doesn't work.."  'Cuz it 
  45.                   does...Trust me..:)  Thanks!
  46.  
  47.      
  48.      ┌─HOW─SCRIPTS─WORK──────────────────────────────────────────────┐
  49.      └───────────────────────────────────────────────────────────────┘
  50.  
  51.       Scripts for Pentasim are simple ASCII text files that the Sysop 
  52.       writes to perform various actions.  In essence, they are a 
  53.       happening from within the game.  When the player chooses the 
  54.       (V)enture Underground option at the Main Menu of Pentasim, the 
  55.       game will pick a random number from 1 to the number of Scripts 
  56.       that are installed, and then execute the event that has been 
  57.       written in the Script file.
  58.  
  59.      
  60.      ┌─USING─SCRIPTS.EXE─────────────────────────────────────────────┐
  61.      └───────────────────────────────────────────────────────────────┘
  62.  
  63.       I have tried to make the process of writing Scripts as easy as 
  64.       possible by including SCRIPTS.EXE.  This program will allow you 
  65.       to do several things:
  66.  
  67.          Install Script Files
  68.          Remove Script Files 
  69.          Write New Script Files
  70.          Edit Existing Script Files
  71.          Test Your Script Files
  72.          View Script File Error Log
  73.  
  74.       You will be able to quickly and easily see which Scripts you have 
  75.       installed as well as install new ones or remove exisiting ones.  
  76.       Keep in mind that SCRIPTS.EXE is NOT an Editor, it utilizes DOS 
  77.       EDIT for writing and editing Scripts.  Most Sysop's should feel 
  78.       right at home working in DOS EDIT :)
  79.  
  80.       In this environment though, it will be much easier for you to work 
  81.       on your Scripts.  In essence, you could go into SCRIPTS.EXE, begin 
  82.       writing a NEW Script, then test what you have done so far.  If 
  83.       there was an error, you would be able to easily view WHICH error 
  84.       happened, go back to editing your Script, and test it again. 
  85.  
  86.       In one session, you would be able to write a NEW Script, test it, 
  87.       debug it, and install it right into the game without ever having 
  88.       to leave the SCRIPTS.EXE environment.  SCRIPTS.EXE is multinode 
  89.       aware, so you can work in it even while a player is online in the 
  90.       game, on another node if you like.  Although, removing Scripts is 
  91.       NOT recommended while a player is in the game :)  In case that 
  92.       player is IN that Script! 
  93.  
  94.       To start the program, simply type:
  95.  
  96.          SCRIPTS
  97.  
  98.       at your DOS prompt.  Be sure that SCRIPTS.EXE remains in your main 
  99.       Pentasim directory and any Script files that already exist are in 
  100.       your SCRIPTS subdirectory.
  101.  
  102.       I also suggest that you print this DOC file in order to use it for 
  103.       reference while you are working in the SCRIPTS.EXE environment.
  104.      
  105.      
  106.      ┌─UNREGISTERED─LIMITS───────────────────────────────────────────┐
  107.      └───────────────────────────────────────────────────────────────┘
  108.  
  109.       Sunrise Door Software has now removed the unregistered limits in 
  110.       Pentasim Script Files.  Upon initial release, you could only
  111.       install 1 Script File if Pentasim was unregistered.
  112.  
  113.       As of v1.1, SCRIPTS.EXE now allows you to install up to the 
  114.       full 21 Script Files.  Enjoy folks!
  115.  
  116.      
  117.      ┌─WRITING─SCRIPTS───────────────────────────────────────────────┐
  118.      └───────────────────────────────────────────────────────────────┘
  119.  
  120.       Now the fun part...
  121.  
  122.       Let's first go over the basic commands that can be used within 
  123.       your Scripts.  Here is a listing of the commands:
  124.  
  125.          
  126.       COMMANDS:                 SUB COMMANDS:          WRAP COMMANDS:
  127.       ========                  ============           =============
  128.          
  129.       DISPLAY   RANDOM          GRANT                  START CHOICE
  130.       INPUT     CAPTURE         FIND                   END CHOICE
  131.       CLEAR     WAIT            WIN                    START DECISION
  132.       CHOICES   PAUSE           LOSE                   END DECISION
  133.       CHOICE    GOTO            TAKEN                  START COMMENT
  134.       INPUT     ROUTINE         VANISH                 END COMMENT
  135.       GIVE      EXIT            NONE
  136.       TAKE      BATTLE
  137.          
  138.  
  139.       Now let's discuss how we would use these commands and what each one 
  140.       represents.
  141.  
  142.       - DISPLAY - 
  143.  
  144.       This command will "display" lines of text to the screen.  DISPLAY 
  145.       should always be followed with the corresponding lines of text.  Be 
  146.       sure that the number you give after the DISPLAY command is equal to 
  147.       the number of text lines you have :)  An additional command of 
  148.       positioning is added to this command as well.
  149.  
  150.       Your text on 1 line should NEVER exceed 70 characters total.  Words 
  151.       do NOT wrap.
  152.       
  153.       In the below example, the command tells the program to display the 
  154.       next "2" lines of text and the "7" indicates that you want the first 
  155.       line of text to be displayed on line 7.  Even though the program 
  156.       starts you out at line 7, this additional command is ALWAYS needed.  
  157.       There is no default for this.
  158.  
  159.       Each additional line AFTER the first line will be automatically 
  160.       incremented by 1 line.
  161.       
  162.          Ex.  DISPLAY,2,7
  163.  
  164.       - CLEAR - 
  165.  
  166.       This command will clear the screen and send a new default ANSI screen 
  167.       ready for more text or whatever.  The cursor positioning will then 
  168.       default back to line 7.
  169.       
  170.          Ex.  CLEAR
  171.       
  172.       - CHOICES - 
  173.  
  174.       This is the number of choices available to the player.  
  175.  
  176.          Ex.  CHOICES,3
  177.  
  178.       - CHOICE - 
  179.  
  180.       This is one of the choices, the corresponding hotkey to be used and 
  181.       the choice text.  If there are 3 CHOICES, then the choices should 
  182.       be listed 1,2,3.  Maximum choices you can have would be 9, since it 
  183.       is single hotkey entry.  Your keys can be anything you like.
  184.  
  185.          Ex.  CHOICE,A,Bag #1   
  186.                    
  187.                      ^   ^
  188.                      |   |
  189.                      |    ------------------ Choice Text to Display
  190.                       ------ Choice Hot Key
  191.                    
  192.       - START CHOICE - 
  193.  
  194.       This will signal the START of the choices you have laid out for 
  195.       the user to make.  This command also has a parameter command after 
  196.       it.  The parameter command represents where you want the choices 
  197.       displayed.
  198.  
  199.       In the below example, if there were 3 choices, the first choice 
  200.       would be displayed on line 10, second on line 11 and third on line 
  201.       13.
  202.       
  203.          Ex.  START CHOICE,10
  204.       
  205.       - END CHOICE - 
  206.  
  207.       This signals the END of the choices, telling the program that we are 
  208.       done with the choices.
  209.       
  210.       - INPUT - 
  211.  
  212.       This tells Pentasim to get the input from the user at this point.  
  213.       INPUT should be issued *AFTER* CHOICES and each CHOICE command.
  214.  
  215.       There is also a SUB command along with this command.  The SUB 
  216.       command is the prompt you want displayed to the user.
  217.       
  218.       There is also another parameter on this command.  In the example 
  219.       below, the phrase "Make Your Selection:" would be displayed on line 
  220.       15 and would wait right after the ":" for the users input.
  221.       
  222.          Ex.  INPUT,Make Your Selection:,15
  223.  
  224.       ****NOTE: It's preferable NOT to use Color Codes with the text
  225.                 portion of your INPUT command.  You CAN, but the program
  226.                 looks at the length of the text field when deciding WHERE
  227.                 to put the cursor.
  228.  
  229.                 The above text would be displayed like this:
  230.  
  231.                    Make Your Selection: x <- The cursor would be where the
  232.                                              x is.
  233.  
  234.                 While, if your command looked like this:
  235.  
  236.                    INPUT,^Make Your Selection:^,15
  237.  
  238.                 With the ^ representing the red color code, it would now
  239.                 be displayed like this, since the ^'s add 2 more characters
  240.                 to the text, even though the ^'s are not displayed to the 
  241.                 user:
  242.  
  243.                    Make Your Selection:   x <- The cursor has been advanced
  244.                                                by 2 because of the ^'s.
  245.  
  246.                 Keep this in mind when using the INPUT command with Color
  247.                 Codes.
  248.       
  249.       - GIVE - 
  250.  
  251.       This option will simply choose something to GIVE to the player.  An 
  252.       item or items will be chosen at random, like Kroons, Health Capsules, 
  253.       etc.  There are ACTION words that are used along with this command.  
  254.       Depending on the theme of your Script, there are a couple of words 
  255.       to choose from.
  256.  
  257.       For example, if it was a magical creature that was giving you 
  258.       something, you would want the text to read something like this: 
  259.       "You are granted 10,000 Kroons!"  In another example, if the user 
  260.       was looking in something, you would want the text to read something 
  261.       like: "You find 10,000 Kroons".
  262.  
  263.       The SUB commands that can be used with GIVE are as follows:
  264.  
  265.          GRANT   <- The player is GRANTED the item
  266.          FIND    <- The player FINDS the item
  267.          WIN     <- The player WINS the item
  268.       
  269.          Ex.  GIVE,FIND 
  270.  
  271.       - TAKE - 
  272.  
  273.       As in the above example, this will take something away from the 
  274.       player.  The program will choose something at random and if the 
  275.       player does not have that, it will go through the list of what they 
  276.       DO have and take something else.
  277.  
  278.       It will always default to Health percentage points if the player does 
  279.       not have ANYTHING.
  280.  
  281.       This command also features SUB commands in order for the text to flow 
  282.       smoother with the theme.  These SUB commands are as follows:
  283.  
  284.          LOSE    <- The player LOSES the item
  285.          TAKEN   <- The item is TAKEN from the player
  286.          VANISH  <- The item VANISHES into thin air
  287.       
  288.          Ex. TAKE,TAKEN
  289.       
  290.       - RANDOM - 
  291.  
  292.       This command will choose for itself at random if it should TAKE or 
  293.       GIVE something to the player.  I think this option is best, so on 
  294.       any given day, the player does not know what will happen if this is 
  295.       used in relation say to a CHOICE situation.
  296.       
  297.       This command must have the corresponding SUB command along with it.  
  298.       The GIVE corresponding SUB command is the one used here, while if the 
  299.       game decides to TAKE something, it will use the corresponding phrase 
  300.       that goes with each GIVE command.
  301.  
  302.       Here's how the phrases are laid out:
  303.  
  304.          GRANT   -   VANISH
  305.          FIND    -   TAKEN
  306.          WIN     -   LOSE
  307.                
  308.       In the below example, the key phrase "granted" will be used because 
  309.       of the GRANT SUB command, if the RANDOM chooses to GIVE something to 
  310.       the player.  If RANDOM chooses to TAKE something, then the SUB 
  311.       command would automatically be represented by VANISH, meaning the 
  312.       phrase might go something like this: "1,000 of your Kroons vanish"
  313.       
  314.          Ex. RANDOM,GRANT
  315.       
  316.       The commands GIVE, TAKE & RANDOM will either GIVE or TAKE the 
  317.       following: 
  318.  
  319.          * Kroons
  320.          * Health Points
  321.          * Health Capsules
  322.          * Power Capsules
  323.          * Food Capsules
  324.          * The MasterChip
  325.  
  326.       - START DECISION - 
  327.  
  328.       This is another WRAP command that tells the program it is time to 
  329.       make a decision and must ALWAYS be wrapped around your COMMAND,ACTION.  
  330.       This MUST be the next line after your INPUT command line.
  331.  
  332.          Ex.  START DECISION
  333.  
  334.       - END DECISION - 
  335.  
  336.       Again this is WRAPped around your COMMAND,ACTION's and MUST be the 
  337.       last command after your COMMAND,ACTION.  It tells the program that 
  338.       we are done making a decision and it's time to move on.
  339.       
  340.          Ex.  END DECISION
  341.       
  342.       ****IMPORTANT: Any blocks within your START DECISION & END DECISION 
  343.                      like this for example:
  344.  
  345.                      A
  346.                      TAKE,TAKEN
  347.                      B
  348.                      RANDOM,GRANT
  349.  
  350.                      Each corresponding HOTKEY listed for the users choice 
  351.                      can only have *1* command after it.  After your END 
  352.                      DECISION, you can then move on with something else.
  353.       
  354.       - GOTO - 
  355.  
  356.       This is a very powerful command in the Pentasim Script Language.  
  357.       GOTO will allow you to move to another section in your Script file, 
  358.       quickly and easily.
  359.  
  360.       GOTO can only be used within a START DECISION - END DECISION.  As in 
  361.       the case of GIVE,GRANT within a DECISION, GOTO is formatted in the 
  362.       same fashion, as a COMMAND,ACTION.  In this case, the COMMAND is GOTO, 
  363.       while the ACTION is the name of your ROUTINE that you want to go to.
  364.       
  365.       Once GOTO is found in the DECISION block, the rest of the block is 
  366.       ignored as well as everything else, UNTIL the ROUTINE command is 
  367.       encountered.  We'll talk about ROUTINE next.
  368.  
  369.       ****NOTE: You can only GOTO a ROUTINE that is placed further down in 
  370.                 your Script.  Thus, you can only GOTO a ROUTINE once.
  371.       
  372.          Ex.  GOTO,MYROUTINENAME
  373.  
  374.       - ROUTINE - 
  375.  
  376.       As noted above, this command is used in conjunction with the GOTO 
  377.       command.  Your Script may include something where the player was to 
  378.       choose from 3 different paths to go down.  The GOTO command, when 
  379.       used in a DECISION block, could GOTO 1 of 3 different ROUTINEs in 
  380.       your Script file.
  381.  
  382.       You can name your ROUTINE anything you wish.  Keep in mind that the 
  383.       program will not know what to do with a ROUTINE command that it 
  384.       encounters unless it has been sent there using the GOTO command.
  385.  
  386.       So, if you had the choice of 3 different paths to take as mentioned 
  387.       above, and had 3 GOTO commands within your DECISION block, be sure 
  388.       that each ROUTINE further down in your Script either EXITed or was 
  389.       sent to another ROUTINE further down, before it encountered a ROUTINE 
  390.       command that it does not know what to do with.
  391.  
  392.       With the sample ROUTINE command line below, the next line and following 
  393.       lines would be executed after a call to GOTO,MYROUTINENAME.
  394.                 
  395.       TEST2.SCR and TEST3.SCR have GOTO and ROUTINE examples in them that 
  396.       will explain this most likely easier than I can in this DOC :)
  397.       
  398.          Ex.  ROUTINE,MYROUTINENAME
  399.       
  400.       - BATTLE - 
  401.  
  402.       This command will allow you to create new enemies for the player to do 
  403.       battle with, within your Script File.  BATTLE can be used as a command 
  404.       by itself, or within a DECISION block, Ex.  When the player chooses 
  405.       option #3 in your Script File.
  406.  
  407.       The battle routine is identical to what the player sees when battling
  408.       Cyborg's in the main game.  It also works exactly the same way.
  409.  
  410.       ****NOTE:  Within Pentasim, when a player executes your Script, if 
  411.                  they have a Power Capsule or Food Capsules, they will be 
  412.                  able to use them.  Within the SCRIPTS.EXE test, these will 
  413.                  not be shown because the TEST player really doesn't have 
  414.                  any stats :)  How the battle goes, player wins, or your 
  415.                  enemy wins is no reflection of how it will go in Pentasim 
  416.                  either.  This all depends on the players stats, weapon, 
  417.                  armor, etc, in the main game.
  418.  
  419.       The format for the BATTLE command, regardless of where it is called 
  420.       is: 
  421.  
  422.          BATTLE,Your Enemy Name
  423.  
  424.       When BATTLE is called, you must provide the enemy name you wish the 
  425.       player to battle...This is BATTLE's ACTION command.  The enemy name 
  426.       can be anything you like.  Keep in mind, when the enemy name is used 
  427.       within the battle it will be used AS IS.  If your enemy name was 
  428.       DeathMaster then it would be displayed like this for example:
  429.  
  430.          Player's Health: 100%   DeathMaster's Health: 100%
  431.                                             ^
  432.                                             |--- The 's is added by Pentasim.
  433.  
  434.       If your enemy needs a description, then you should do so BEFORE you 
  435.       call BATTLE.
  436.  
  437.       If the player defeats your enemy, then the player will get Kroons from 
  438.       the enemy.  The amount is a random number depending on where the player 
  439.       is in the game.  If the player loses to your enemy, then they will be 
  440.       CAPTURED and the Script will automatically exit.  The player will then 
  441.       be done for the day.  They will also lose all Kroons they had on hand 
  442.       at the time.
  443.  
  444.       A couple of other small things to note:
  445.  
  446.       You should always call WAIT after your call to BATTLE.  Ex.  If you had 
  447.       3 choices for the player to make, 1 choice gave them something, 1 
  448.       choice went to another ROUTINE and the third choice was a BATTLE 
  449.       command, then after your END DECISION command you will have to place 
  450.       a WAIT command.
  451.  
  452.       The choice that goes to another ROUTINE will of course ignore the WAIT
  453.       command and just head to the ROUTINE that you called, while the other 
  454.       2 NEED a WAIT command.  If you GIVE the player something, the WAIT 
  455.       command will allow them to see what they have got before proceeding 
  456.       while the WAIT command will allow them to see that they have defeated 
  457.       your enemy and how many Kroons they received.  Makes sense right?
  458.  
  459.       If the player LOST the BATTLE, then they will be told so, how many 
  460.       Kroons they lost and the fact that they have been captured.  The game 
  461.       will PAUSE for an automatic 5 seconds here and then kick them right 
  462.       out of the game.
  463.  
  464.       After your call to WAIT a CLEAR command would be in order.  To simply 
  465.       CLEAR the remnants of the BATTLE or the GIVE from the screen and start 
  466.       fresh.
  467.  
  468.          Ex. BATTLE,Enemy Name
  469.  
  470.       TEST4.SCR includes BATTLE examples which you can work from.
  471.       
  472.       - CAPTURE - 
  473.  
  474.       In Pentasim, being captured is basically the same as being killed in 
  475.       other RPG games.  Once a player is captured, they are unable to play 
  476.       anymore that day and they will lose all on hand Kroons.  Try not to be 
  477.       mean with this option :)  Once this option is called, the Script will 
  478.       end there and the player will be done for the day.
  479.  
  480.       When the CAPTURE command is seen by the program, this line will be 
  481.       displayed:
  482.  
  483.          2 Cyborg's appear and haul you off to the Detention Centre!
  484.  
  485.       Keep this in mind when you use the CAPTURE command.  Remember, players 
  486.       do NOT get KILLED.  If for instance in your Script, a boulder dropped 
  487.       out of the sky because of the option they chose and landed on them :) 
  488.       (OUCH!)...then you could say something like "a Boulder drops out of 
  489.       the sky and lands right on top of you...Your health goes waaay down."  
  490.       Then issue the CAPTURE command and the above line will be written next.
  491.                 
  492.       Since this is a command that can be placed along with other 
  493.       COMMAND,ACTION statements as in a DECISION, the formatting must remain 
  494.       contstant.  As there is no SUB command for CAPTURE, the SUB NONE is 
  495.       used.  Meaning, once CAPTURE is found, it performs it's own ACTION and 
  496.       does not need an ACTION companion.  There are 2 ways to call CAPTURE 
  497.       within your Script, depending on where you call it.
  498.  
  499.       The first example below would be used within a DECISION while the other 
  500.       can be called anywhere else in the Script and does not need the 
  501.       corresponding NONE on the end of it.
  502.       
  503.          Ex.  CAPTURE,NONE
  504.  
  505.          Ex.  CAPTURE
  506.       
  507.       - WAIT - 
  508.  
  509.       This command will simply wait for a key to be pressed before it 
  510.       proceeds.  This command displays the Pentasim "Any Key" prompt centered 
  511.       on line 23.  There is no need for you to display anything when calling 
  512.       WAIT.
  513.       
  514.          Ex. WAIT
  515.  
  516.       - PAUSE - 
  517.  
  518.       This command will put in a pause in your Script.  The length of the 
  519.       pause is determined by the number following the PAUSE command.
  520.  
  521.       In the example below, the Script would pause for 3 seconds before 
  522.       proceeding to the next line of Script.
  523.  
  524.       Remember, PAUSEing too long might make the user think the game has 
  525.       locked up and they will drop carrier, so be careful with how long you 
  526.       PAUSE for.
  527.       
  528.          Ex. PAUSE,3
  529.  
  530.       - START COMMENT - 
  531.  
  532.       This command will allow you to enter as many lines of comments as you 
  533.       wish.  Be sure that your comments are always wrapped in this and the 
  534.       END COMMENT command.
  535.  
  536.       ****NOTE: Comment blocks should not be placed where the program EXPECTS 
  537.                 to find another command.  Ex.  When CHOICES is first called, 
  538.                 comment blocks will not be allowed until after your END 
  539.                 DECISION command, as all above noted commands are expected 
  540.                 after a call to CHOICES one after another, with NOTHING in 
  541.                 between them.
  542.  
  543.                 If comments are needed, make them BEFORE a call to CHOICES or 
  544.                 AFTER your END DECISION command.
  545.       
  546.          Ex.  START COMMENT
  547.       
  548.       - END COMMENT - 
  549.  
  550.       Tells the program that you are done writing comments and it's time to 
  551.       move on.
  552.       
  553.          Ex.  END COMMENT
  554.       
  555.       - EXIT - 
  556.  
  557.       Last but not least, this command placed anywhere in the Script, will 
  558.       cause the Script to be stopped and exited.
  559.              
  560.       This command, like CAPTURE, can also be called within a DECISION.  For 
  561.       example, one of your options may be for the user to quit the Script.  
  562.       Example 1 below is used within a decision, while just the simple EXIT 
  563.       with no SUB command is used any where else in your Script.
  564.              
  565.       This should ALWAYS be the LAST thing your Script has in it as well.
  566.  
  567.          Ex. EXIT,NONE
  568.       
  569.          Ex. EXIT
  570.  
  571.       ****NOTE: Some important things to remember...
  572.                 
  573.          *  Keep track of your lines.  If you have hit line 22 then
  574.             you should use the CLEAR command to start off with a
  575.             fresh screen.  Otherwise the Script will exit with an
  576.             ERROR.
  577.      
  578.          *  NEVER use "" quotes like these in any text OTHER than
  579.             the text that is used in conjunction with the DISPLAY
  580.             command.  The Script will exit with an ERROR on this
  581.             one for sure :)
  582.      
  583.          *  Be sure there are NEVER any BLANK lines in your Script.
  584.             Each line should be listed right after the last line.
  585.             If you want to put comments in, use the START COMMENT
  586.             END COMMENT wrap commands.
  587.      
  588.          *  You are limited in HOW many times something can be executed
  589.             in your Script File as well.  Each Script File is allowed 
  590.             a maximum of 5 BATTLE's and 2 GIVE, TAKE or RANDOM commands.
  591.             Basically, the player can only do BATTLE 5 times in your
  592.             Script and be given or have something taken away 2 times.
  593.             That's not to say that you can't have 10 DECISION blocks
  594.             with numerous GIVE or TAKE commands, but once a command is
  595.             executed then the counter starts :)
  596.           
  597.             This was put in place so things don't get out of hand and
  598.             no one has an unfair advantage.  Nothing worse in my opinion
  599.             than a 3rd party addon giving the player a gizillion of
  600.             something!
  601.           
  602.          *  We haven't discussed it yet, but keep in mind anywhere
  603.             you can enter text, either to be DISPLAYed or along with
  604.             the INPUT command for example, you can use color codes.
  605.                 
  606.      
  607.      ┌─COLOR─CODES───────────────────────────────────────────────────┐
  608.      └───────────────────────────────────────────────────────────────┘
  609.      
  610.       At any time in your text that you display to the screen, you can use 
  611.       color codes to spice things up a bit.  Here are the codes:
  612.  
  613.          ~ = Blue               ` = Green               @ = Cyan  
  614.          ^ = Red                | = Magenta             { = Yellow  
  615.          } = White              * = Low Intensity       % = Blinks
  616.  
  617.       The "*" Low Intensity and the "%" Blinks commands are used in 
  618.       conjunction with the other color commands.  Here are some examples of 
  619.       using the color codes.
  620.  
  621.          The ^red^ fox jumped over the }white} fence!
  622.      
  623.       Each color is started with it's code and ended with the same code.  
  624.       This tells the program that you want to end that color.  The above 
  625.       example would display most of the line in the default low intensity 
  626.       Cyan color that is used throughout most of Pentasim.  The "red" would 
  627.       be displayed in Red, while the "white" would be displayed in white.
  628.  
  629.       Here is another example:
  630.          
  631.          The ~red fox jumped~ over the white |fence|!
  632.  
  633.       This line would display "red fox jumped" in Blue and "fence" in 
  634.       Magenta.  The rest of the line would be in the default color.
  635.  
  636.       Let's say you wanted to display the "red" in dark red and "fence" you 
  637.       wanted to blink in Blue.  You would do this:
  638.  
  639.          The *^red^ fox jumped over the white %~fence~!
  640.      
  641.       The Low Intensity command as well as the Blinking command always 
  642.       proceed the color command and is only entered once.  There is no need 
  643.       for a second "*" after red for example.
  644.      
  645.       Hopefully the above examples should explain the use of color codes well 
  646.       enough.  Play around with them and see what you can come up with.
  647.      
  648.       Keep in mind that the 70 character limit for each display line only 
  649.       includes the actual TEXT.  The color codes do not count as a character, 
  650.       as they of course are not displayed on the screen.
  651.  
  652.      
  653.      ┌─SCRIPT─EXAMPLE────────────────────────────────────────────────┐
  654.      └───────────────────────────────────────────────────────────────┘
  655.  
  656.       Here is a basic example of what you can do with Scripts in Pentasim.  
  657.       You can also check out the TEST.SCR, TEST2.SCR, TEST3.SCR & 
  658.       TEST4.SCR files in the SCRIPTS subdirectory for more examples.
  659.  
  660.       ****NOTE: The example is broken up so it can be more easily  
  661.                 explained...There should NEVER be any BLANK lines in your 
  662.                 Script file.
  663.  
  664.  
  665.       DISPLAY,2,7      <- Displays the next 2 lines of text starting at 
  666.                           line 7.
  667.  
  668.       You find yourself in an underground @valley@ with @3@ large rocks 
  669.       directly in front of you.  Which @rock@ do you turn over?
  670.  
  671.       *******************************************************************
  672.       
  673.       CHOICES,3     <- Tells the game that there are 3 choices the user can 
  674.                        make.
  675.  
  676.       START CHOICE,10  <- This is the WRAP command that MUST be at the start 
  677.                           of your choices and always immediately follows the 
  678.                           CHOICES command.  The "10" tells the game to start
  679.                           displaying the choices at line 10.
  680.  
  681.       CHOICE,A,Rock #1   <- These are the corresponding 3 choices that the 
  682.                             user can make.  Each line is automatically
  683.       CHOICE,B,Rock #2      incremented by 1.  The "A", "B", and "C" are
  684.                             each choices HOT KEYS.
  685.       CHOICE,C,Rock #3      
  686.                             Meaning if the user hits the A key, then they 
  687.                             have selected choice number 1.
  688.                       
  689.                             "Rock #1" and so on is the text to display FOR 
  690.                             each choice, so the user knows what it is they 
  691.                             are choosing.
  692.  
  693.  
  694.       END CHOICE    <- This command must ALWAYS end your CHOICE selections,
  695.                        in order to tell the game that we are done choosing
  696.                        and it's time to move on.
  697.  
  698.       INPUT,Make your Choice:,13    <- Tells the game that it's time to get
  699.                                        input from the user.  "Make Your 
  700.                                        Choice:" is the prompt that will be 
  701.                                        displayed to the user, while the "13" 
  702.                                        is the row to display the prompt on.
  703.  
  704.       START DECISION    <- Tells the game that we now want to make a decision 
  705.                            on whatever HOTKEY the user chose.  This MUST be 
  706.                            called before you list your decisions and what 
  707.                            happens with each one.
  708.  
  709.       A            <- The corresponding HOTKEY that was listed above for
  710.                       choice 1.
  711.  
  712.       GIVE,FIND    <- What happens when the user chooses that key.  In this 
  713.                       case the game would GIVE them something and use the 
  714.                       SUB command FIND when describing what they get.  This 
  715.                       would be very appropriate for THIS Script, since the 
  716.                       user is looking under rocks....He/she would then 
  717.                       "find" something.
  718.                        
  719.       B
  720.       GIVE,FIND
  721.       C              <- More decision keys and what happens with each one.
  722.       GIVE,FIND
  723.  
  724.       END DECISION  <- Tells the game we are done making a decision and it is
  725.                        time to move on.  This MUST be called once you have 
  726.                        listed all of your decisions and what happens with 
  727.                        each one.
  728.       *********************************************************************
  729.  
  730.       ****NOTE: Everything between the "*"'s MUST be blocked together when 
  731.                 used in ANY Script file.  I suppose I could have put WRAP 
  732.                 commands around this too, but decided not to :)  Rememeber:  
  733.                 NO Comment blocks or ANY other commands can be entered within 
  734.                 this block.  Anytime you give the user a choice and make them 
  735.                 make a decision, this entire block is to be used in the above 
  736.                 order!
  737.  
  738.       WAIT   <- Causes the "any Key" prompt to be displayed on line 23, 
  739.                 centered, as in the main Pentasim game.  As soon as the user 
  740.                 hits any key, the program will resume.
  741.  
  742.       EXIT   <- Exits the Script file.  Meaning we are done!  This MUST be 
  743.                 the last thing listed in the Script file.
  744.  
  745.       Now....Since we really made a mess of the actual file with all of the 
  746.       describing...:), here's how it should look.
  747.  
  748.  
  749.       DISPLAY,2,7      
  750.       You find yourself in an underground `valley` with }3} large rocks 
  751.       directly in front of you.  Which @rock@ do you turn over?
  752.       CHOICES,3     
  753.       START CHOICE,10   
  754.       CHOICE,A,Rock #1   
  755.       CHOICE,B,Rock #2   
  756.       CHOICE,C,Rock #3   
  757.       END CHOICE       
  758.       INPUT,Make your Choice:,13     
  759.       START DECISION    
  760.       A            
  761.       GIVE,FIND    
  762.       B
  763.       GIVE,FIND
  764.       C              
  765.       GIVE,FIND
  766.       END DECISION  
  767.       WAIT   
  768.       EXIT    
  769.  
  770.       Wasn't that easy?  Yes, you can slap me now...:)  Read over this doc a 
  771.       few times and do some small examples yourself and you'll see that it is 
  772.       pretty easy once you get the hang of it.  Easier than programming...I 
  773.       can vouch for that!
  774.  
  775.      
  776.      ┌─DISTRIBUTING─SCRIPTS──────────────────────────────────────────┐
  777.      └───────────────────────────────────────────────────────────────┘
  778.  
  779.       You can distribute Scripts any way you like.  Any Scripts created for 
  780.       use with Pentasim are Public Domain.  Script files created for Pentasim 
  781.       are not to be SOLD nor are any fees to be charged for them.
  782.  
  783.       If you create something you are rather proud of, then by all means ZIP 
  784.       it up with a file_id.diz and upload it to other BBS's or pass it along 
  785.       to your friends.
  786.  
  787.       The nice thing about Scripts written for Pentasim, is that they allow 
  788.       the Sysop to customize their game, while others can get a copy and use 
  789.       it in their game quite easily as well. 
  790.  
  791.       This is one of the main reasons I chose NOT to compile the Script 
  792.       files.  It allows others to make changes in a Script file they may have 
  793.       gotten from somewhere else and also to drive the users nuts....:)  Say 
  794.       for example that you had something similar to the Script above, but 
  795.       instead of using GIVE in all three choices, choice 2, you placed a TAKE 
  796.       command.  So a user has been able to play the Script several times and 
  797.       now knows that if he/she chooses option #2, they will get something 
  798.       taken away from them.  Wouldn't it be fun to see the look on their face 
  799.       after you decided to go into the Script and quickly switch the commands 
  800.       around after a week or so....:)
  801.  
  802.      
  803.      ┌─SCRIPT─ERRORS─────────────────────────────────────────────────┐
  804.      └───────────────────────────────────────────────────────────────┘
  805.  
  806.       Here is a listing of the ERRORS that you will see written to the Script 
  807.       ERROR file which will be placed in the Pentasim main directory.  It will 
  808.       be called: 
  809.  
  810.          SCRIPTS.ERR.
  811.  
  812.       - Invalid Row Positioning -
  813.  
  814.       Anywhere you have control of the positioning on the screen, as in the
  815.       DISPLAY,2,7 command or if your DISPLAY lines or CHOICE lines exceed 
  816.       the 22 limit.  Ex.  You try to DISPLAY 6 lines of text starting at 
  817.       line 20.
  818.  
  819.       START CHOICE Command Missing 
  820.    
  821.       Your START CHOICE command is either missing or is improperly placed.
  822.  
  823.       - Invalid Command After END CHOICE -
  824.    
  825.       The INPUT command does not follow your END CHOICE command.  
  826.  
  827.       - Missing START DECISION Command -
  828.    
  829.       Your START DECISION command is either missing or is improperly placed.
  830.  
  831.       - Invalid Action Command -
  832.    
  833.       Your ACTION command is not from the list of valid choices or is missing 
  834.       entirely.
  835.  
  836.       - Invalid or Missing Command Parameter -
  837.  
  838.       You have placed a command parameter where it is not valid or have not 
  839.       used a parameter from the command list.
  840.       
  841.       - Script File Not Found -
  842.  
  843.       The Script file that is installed and has been chosen for the user is 
  844.       not in the SCRIPTS subdirectory.
  845.  
  846.       - Too Many BATTLE Commands -
  847.  
  848.       You are attempting to allow the user to battle more than the allowed 5
  849.       battles per Script File.
  850.  
  851.       - Too Many GIVE, TAKE or RANDOM Commands -
  852.  
  853.       You are attempting to give or take items more than the allowed 2 times 
  854.       per Script Files.
  855.  
  856.  
  857.      ┌─FINAL─WORD────────────────────────────────────────────────────┐
  858.      └───────────────────────────────────────────────────────────────┘
  859.  
  860.       I know that this is a lot to take in and some of you may be thinking...
  861.       "I thought he said this was EASY?"
  862.  
  863.       I still say that it IS easy compared to some other Scripting Languages 
  864.       out there...Even if it doesn't feel like it right now :)  Keep in mind 
  865.       that there IS a lot to take in here and some of it will take a little 
  866.       time.
  867.  
  868.       You ARE learning a language after all and you may spend several hours 
  869.       before you feel comfortable with it, but that's still better than 
  870.       spending several YEARS to learn a programming language isn't it?
  871.  
  872.       Play with it, have fun with it...Learn from the examples in the SCRIPTS
  873.       subdirectory and look at what OTHER people are doing and hopefully you 
  874.       WILL have some fun and make Pentasim that much MORE fun on your BBS!
  875.  
  876.       Some things may be added or changed at any point within the Pentasim
  877.       Scripting Language.  If anyone has any ideas, suggestions, or even 
  878.       wishes for things you would like to see added or changed, let me know.  
  879.       I'm always open to suggestions!
  880.  
  881.       Good luck and take care folks...
  882.